home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / struct.tex < prev    next >
Text File  |  1993-01-28  |  9KB  |  248 lines
  1. % Struct.tex copyright 1992 Victor Eijkhout
  2. %
  3. \Chapter The structure of Lollipop
  4.  
  5. Lollipop provides tools for realizing the style or layout of a
  6. document. Some of these tools are macros ready to be used by the end
  7. user; they concern for instance selection of fonts.
  8. Others, the `generic constructs', are for the style designer so that
  9. she can use them to program the macros for the user.
  10.  
  11. \Section[sec:doc-start-stop] Lollipop Files
  12.  
  13. Any Lollipop document has to have a \cs{Start} and \cs{Stop} command.
  14. Before the \cs{Start} there can be style definition commands, but no
  15. text. For a number of reasons it is advisable to put as much of the
  16. style definition before the \cs{Start} command as possible. You can
  17. do that easily by loading the style as an input file, or by first
  18. dumping it as a format (see section~\ref[sec:style-dump]).
  19.  
  20. \ImpNote
  21. Before the \cs{Start} command, \cs{everypar} contains an error
  22. message. The start command installs the default value for
  23. \cs{everypar}.
  24. \ImpNoteStop
  25.  
  26. Both the start and the stop file load the \file{.aux} auxiliary file.
  27. None of this should concern you, really. Expert users who want to
  28. have certain actions performed at the start of the document may want
  29. to use \refcs{StartCommand} to specify what they wish done. See
  30. section~\ref[sec:adapt-distance] for an example.
  31.  
  32. \Section Generic Constructs
  33.  
  34. \label[generic:construct]\label[option:macro]
  35. There are five `generic constructs': headings, lists, text blocks, page
  36. grids, and external items. For each construct type there is a defining
  37. command, for instance \cs{DefineHeading}
  38. which is followed a list of `options', terminated by the word `Stop'.
  39.  
  40. Options (possibly with values) have to be separated by a
  41. space or a line end; the keyword \opt{Stop} has to be followed by a
  42. space or a line end.
  43. Options may have zero, one or two values; if there are values, then
  44. the first one is separated from the option by a colon, the second is
  45. separated from the first by an equals sign.
  46.  
  47. \Ver>\DefineFoo:Bar optiona optionb optionc:value
  48.     optiond:valuea=valueb optione
  49.     optionf Stop<Rev
  50.  
  51.  As a result of this definition, a command
  52. \cs{Bar} is created. If the \con{Foo} construct was a \con{List} or
  53. \con{TextBlock}, an additional command \cs{BarStop} is created.
  54.  
  55. This command can then be used in the ordinary way, for instance
  56. after \ver>\DefineHeading:Foo> you can type
  57. \Ver>\Foo The title<Rev and after \ver>\DefineList:Foo> you can type
  58. \Ver>\Foo
  59. \item One item
  60. \item And another
  61. \FooStop<Rev
  62.  
  63. \ImpNote
  64. Actually, this `Stop' business can be customized for other languages.
  65. The file \file{tools} has the following lines:
  66. \Ver>
  67. \def\stop@command@suffix{Stop}
  68. \def\stop@command{\@command\stop@command@suffix}<Rev
  69. \ImpNoteStop
  70.  
  71. \Section Options
  72.  
  73. Options are mostly used to specify how a construct will look. Some
  74. options, for instance \opt{title}, indicate material that will appear
  75. on the page. Other options are interpreted as commands, for instance
  76. \opt{IndentAfter:yes} in the definition of a heading indicates that
  77. the first paragrah after such a heading will indent.
  78.  
  79. In addition to keywords that only exist as options, commands can
  80. be used as options. Also, single characters are accepted as options.
  81. For instance a definition of a subsection heading can contain: 
  82.  
  83. \Ver>\DefineHeading:SubSection 
  84.     [...]
  85.     SectionCounter . SubSectionCounter
  86.     [...] Stop<Rev
  87. (Here and later the \n{[...]} will denote arbitrary omitted text.)
  88. This definition contains the commands \cs{SectionCounter} and
  89. \cs{SubSectionCounter} and the \n{.} character.
  90.  
  91. If a number of options appears together in a number of constructs it
  92. is convenient to have an abbreviation for them. This can be done with the command
  93. \refcs{OptionsMacro} as follows. The options that appear together are
  94. given a common name
  95.  \Ver>\OptionsMacro:baz=optiona optionb:value optionc
  96.     Stop<Rev
  97. (be sure to leave
  98. no spaces around the equals sign) and this name is then used as
  99.  \Ver>    macro:baz<Rev
  100. in the option list wherever the options are needed. 
  101.  
  102. This is for
  103. instance a good way of specifying identical white space around all
  104. sorts of constructs without duplicating the typing each time.
  105. However, it is only for your convenience: it doesn't save any \TeX\
  106. resources or processing time.
  107.  
  108. \Section[sec:error-msg] Popular error messages. Not!
  109.  
  110. Lollipop is a macro package on top of an existing program, \TeX.
  111. Therefore it is inevitable that you will get \TeX\ error messages
  112. every once in a while. Some of these may confuse you.
  113.  
  114. Here are a few of the errors that I~keep making.
  115.  
  116. \SubSection Missing \cs{endcsname} inserted
  117.  
  118. If you forget the second parameter in a \cs{Distance} or
  119. \cs{SetCounter} command, writing for instance
  120.  \Ver>\Distance:TheWidth<Rev
  121. instead of \Ver>\Distance:TheWidth=15pt<Rev
  122.  \TeX\ will scan
  123. forward, and it can easily bump into something that is highly
  124. unexpected given the context. If this is a \cs{def} or \cs{Define...}
  125. command, a `missing \cs{endcsname}' results. If a blank line follows
  126. the incomplete declaration, the following section applies.
  127.  
  128. \SubSection  Paragraph ended before something was complete
  129.  
  130. \TeX\ has found a blank line (or a~\cs{par} command) where this was
  131. not expected. See for instance the previous section.
  132.  
  133. \SubSection Missing number
  134.  
  135. You have used something that you thought was the name of a control
  136. sequence, but it wasn't. Example:
  137. \Ver>\Distance:parskip=parundent<Rev
  138. Since \cs{parundent} is undefined, \Lollipop\ thought you were
  139. writing something like
  140.  \Ver>\Distance:parskip=5pt<Rev
  141.  
  142. And yes, the message refers to `number' even though what is missing
  143. is a distance.
  144.  
  145. \ImpNote
  146. \iSection Defining Generic Constructs
  147.  
  148. The \cs{Define...} commands are not defined explicitly, instead they
  149. are generated by a call such as
  150. \Ver>    \@GenericConstruct{Heading}<Rev
  151. Full definition:
  152. \Ver>\def\@GenericConstruct#1{<Rev
  153. to be used as \ver>\@GenericConstruct{Foo}>;
  154. \Ver>    \append@to@list{@gencons}{\\#1;}<Rev
  155. book keeping of existing generic constructs;
  156. \Ver>    \csarg\newtoks{#1@defaults}
  157.     \csn #1@defaults\ecs{}<Rev
  158. default commands to be executed whenever 
  159. an instance of this construct
  160. is defined;
  161. \Ver>    \csarg\def{add@#1@default}##1%
  162.              {\append@to@list{#1@defaults}{##1}}<Rev
  163. the command \cs{add@Foo@default}
  164. to add defaults for this construct;
  165. \Ver>    \Install@Noops{#1}<Rev
  166. possibility to generate error msgs for the use of an option that is
  167. not allowed for this type of construct;
  168. \Ver>    \csarg\def{Define#1}:##1 {<Rev
  169. instances of this construct will be defined
  170. by a statement like \ver>\DefineFoo:Bar>;
  171. \Ver>        \def\@name{##1}\def\@class{#1}
  172.         \Tmessage[def]{Defining a #1: ##1}<Rev
  173. \ver>DefineFoo:Bar> leads to \cs{@name} begin \n{Bar},
  174. \cs{@class} being \n{Foo};
  175. \Ver>        \the\generic@defaults
  176.         \csarg\the{#1@defaults}<Rev
  177. unpack token lists of generic and specific default actions;
  178. \Ver>        \Get@Items}<Rev
  179. start recursive processing of list of options. This ends the
  180. definition of \cs{DefineFoo}; the definition of 
  181. \cs{@GenericConstruct} ends with
  182. \Ver>    \csarg\def{@#1Option}##1%
  183.        {\csarg\def{#1@##1}####1####2}<Rev
  184. which defines the \cs{@FooOption} macro; see~\ref[imp:option].
  185. \Ver>    }<Rev
  186.  
  187. \iSection Items Processing
  188.  
  189. Processing the list of items is recursive; at the end some concluding
  190. actions have to be taken, mostly the actual definition of the
  191. construct.
  192.  
  193. First we have to filter out empty arguments, which can be caused by
  194. the use of option macros (\ref[option:macro], \ref[imp:option:macro]).
  195.  
  196. \Ver>\def\Get@Items#1 {\if\EmptyList{#1}\let\get@next@item\Get@Items
  197.     \else\def\get@next@item{\@Get@Items#1 }\fi
  198.     \get@next@item}<Rev
  199.  
  200. Next, check if the argument is \opt{Stop} (defined by
  201. \ver>\NewDummy{Stop}>, \ref[imp:new:dummy]), in which case you
  202. have reached the end of a generic definition, and can start performing
  203. the final rites. Otherwise, dissect this option item 
  204. and go on with the rest
  205. of the options.
  206. \Ver>
  207. \def\@Get@Items#1 {\let\get@next@item=\Get@Items
  208.     \csarg\ifx{#1}\Stop
  209.           \the\generic@stop@defaults
  210.           \let\get@next@item=\relax
  211.     \else \Item@or@Macro#1::. \fi \get@next@item}<Rev
  212.  
  213. The \n{::.} concluding \cs{Item@or@Macro} accomodates one,
  214. possibly empty, argument.
  215.  
  216. \iSection Options\label[imp:option]\label[imp:option:macro]
  217.  
  218. Options can either be specific, defined as
  219. \Ver>\@FooOption{Bar}{ [...] }<Rev
  220. in which case the option \opt{Bar} can only be used inside
  221. a call to \cs{DefineFoo},
  222. or they can be generic, defined as
  223. \Ver>\@GenericOption{Bar}{ [...] }<Rev
  224. For both definitions, the definition text can use up to two parameters.
  225. Parameters are given to the options as
  226. \Ver>    optiona:par1 optionb:par1=par2<Rev
  227.  
  228. Specific options are defined by the line
  229. \Ver>
  230.     \csarg\def{@#1Option}##1%
  231.          {\csarg\def{#1@##1}####1####2}<Rev
  232. in \cs{@DefineGenericConstruct}; a call
  233. \Ver>\@FooOption{Bar}{ ... }<Rev
  234. expands to
  235. \Ver>\def\Foo@Bar#1#2{ ... }<Rev
  236. Generic options are defined by the
  237. following command:
  238. \Ver>\def\@GenericOption#1{
  239.     \append@to@list{@GenericOptions}{\\#1;}
  240.     \csarg\def{Option@#1}##1##2}<Rev
  241. A call
  242. \Ver>\@GenericOption{Bar}{ ... }<Rev
  243. expands to
  244. \Ver>\def\Option@Bar#1#2{ ... }<Rev
  245.  
  246. \ImpNoteStop
  247.  
  248.